The purpose of this tutorial is to get you started creating a new program before you become overwhelmed by the detailed on-line documentation in later topics. The program will add flesh and bones to the "Summary" presented in the previous topic. We assume here that you've read all of the "Startup" topics, but it is not necessary that you understood everything that you read. The examples below are in C, but a complete "Tutorial" project is included on the ViewIt master disks for each of the major languages and compilers supported (you should go ahead and print this "Tutorial" source now if you anticipate having any problems following the C code below).
The Objective
Our objective is to take you through the steps required to create a simple but powerful program that uses ViewIt and FaceIt to support its windows and menus. When finished, you should be impressed by how little code was required to support the program, and will better appreciate why ViewIt is one of the most powerful and elegant of all Mac programming tools. If you run into problems, compare your work with the finished "Tutorial" projects.
The first few steps of the tutorial are concerned with creation of the resource and project files needed by programs using ViewIt and other FaceWare modules.
1. FaceWare File
The first thing we need to do is to make the modules that you purchased from FaceWare available to all of the programs that you will be developing.
Step 1. If you haven't already done so, put a copy of the "FaceWare" file in your active System folder. (Use the copy on the ViewIt master disk, not the Utilities disk.)
If you later get a message that on-line documentation, editing code, or a module is missing, then you may need to add more stuff to the FaceWare file using the "MoveIt" program.
Further information:
Startup -> What is FaceWare?
Startup -> Where do they live?
Startup -> Resource Files -> The FaceWare File
ViewIt -> Resources
2. Resource File
The next thing we need is a resource file in which we'll put all of our program-specific resources. To start with, we'd like as little junk in this file as possible, so let's use the "Minimum" program's resource file.
Step 2. Duplicate the "Minimum.Rsrc" file and rename it by replacing "Minimum" with a new program name. We will use "Tutorial", but you use whatever suits you.
Put this resource file, "Tutorial.Rsrc", in the folder that will contain the compiled application.
Further information:
Startup -> Resource Files -> Temporary Res Files
ViewIt -> Resources
3. Project Files
The next thing we need is a set of project files that contains the minimum code required to make use of ViewIt and FaceIt. Again the "Minimum" program is a good place to start.
Step 3. Duplicate the "MinimumXY" source file & rename it by replacing "Minimum" with your new program name. If a project or make file is also needed, also duplicate the "Minimum" project or make file and rename it, and then open this project or make file and fix any names in it to conform to your new program name.
If using THINK C, for example, you'll have a "TutorialLC.π" project and a "TutorialLC.c" source file. If using LS FORTRAN, you'll have a "TutorialLF.make" make file and a "TutorialLF.f" source file. (The exact file names you use are not important, just the relationship between the resource, source, and project file names.)
4. Compile & Run
One of the great features of using ViewIt and FaceIt is that nearly all of the interface-related code in your programs will be program-specific (i.e., it's the minimum amount of code you'd need even if not using our stuff!). So far, the "Tutorial" program doesn't do anything program-specific, so it contains very little code (we show C here, but Pascal and FORTRAN are very similar):
#include "FaceStorLC.h"
extern struct FaceRec fRec;
main()
{
strcpy(fRec.uName, "Tutorial.Rsrc");
FaceIt(0,DoInit,0,0,0,0);
for (;;) {
FaceIt(0,DoLoop,0,0,0,0);
}
}
where we have changed the res file name from "Minimum.Rsrc" to "Tutorial.Rsrc".
Step 4. Open "Tutorial" project, change the resource file reference from "Minimum.Rsrc" to "Tutorial.Rsrc", and then compile and run the "Tutorial" program.
If you have any problems compiling or running the program, review the above steps and go back and read the "Recompiling Demos" topic in "Getting Started" which describes some of the problems you might encounter.
Further information:
Startup -> How do I meet one?
Startup -> Minimum Code
Startup -> Include Files
Startup -> Initializations
Startup -> Event Handling
FaceIt -> Initializations
FaceIt -> The Main Loop
Commands -> Program Commands -> DoInit, DoLoop
The next few steps illustrate how to add menus, windows, and the code to support these interface elements.
5. Main Menus
The main menu bar typically contains menu items that are either program-wide and always available to the user (such as "Quit"), or are shared by different editable controls (such as "Open", "Cut", "Copy", etc.). The MENU resources associated with these main menus must be edited with a resource editor from outside the program. If numbered in sequence beginning with resource ID 1001 and menu ID 101, then FaceIt will load these MENU resources into the main menu bar on DoInit.
Step 5. Open the "Tutorial.Rsrc" file with ResEdit or other resource editor and add a new MENU resource. Assign resource ID 1005 and menu ID 105 to this MENU so that it is auto-loaded by FaceIt when DoInit is called. Set the menu title to "Tutorial" and add one new item to it named "Open Dialog".
If working with ResEdit, you can use "Duplicate" to duplicate an existing menu and "Get Resource Info" to change its resource ID. To change the menu's internal menu ID, double-click the MENU resource to edit it, and then choose "Edit Menu & MDEF ID" to open a dialog that supports editing of the menu's menu ID. Now rerun the "Tutorial" program to see your new menu.
Beginner's Note: If new to Mac programming, you may find the use of 3 different menu-related "ID"s to be confusing:
"MENU ID" = MENU resource ID ("1005" above)
"menu ID" = internal menu ID number ("105" above)
"MDEF ID" = MDEF resource ID of code that supports menu
The "MENU ID" will always uniquely identify a MENU resource. The "MDEF ID" is typically 0, which corresponds to Apple's standard MDEF. The "menu ID" is the number returned to your program in uMenuID from program menu items, as described below. For program's using FaceIt, the main menus typically have MENU ID's 1001, 1002, ..., with corresponding internal menu ID's of 101, 102, ...
Further information:
FaceIt -> Initializations -> Menu Initialization
6. Menu Handling
On DoInit your main menus get loaded. Selections from these menus are automatically handled by ViewIt, FaceIt, and other modules if the item selected is a "standard" item (i.e., if it has "#n" after it in the MENU resource where "n" is an integer). If the item is not a standard item (such as the "Open Dialog" item), then it returns a message from DoLoop when selected.
Step 6. Add program code after DoLoop to handle selection of the "Open Dialog" program menu item (uMenuID = 105, uMenuItem = 1).
This means add a case or if...else block after DoLoop to look for messages from program menu items:
for (;;) {
FaceIt(0,DoLoop,0,0,0,0);
if (fRec.uMenuID == 105)&&(fRec.uMenuItem == 1))
{
}
}
where uMenuID and uMenuItem are elements of the global fRec record used by all FaceWare modules. Note how one new line of code was added to handle the one new menu item. This illustrates how every line of code that you add is connected in some way to a user interface element that you also added.
Further information:
FaceIt -> The Main Loop
FaceIt -> Menu Handling
7. Modal Window
This help window is a "modeless" window since it does not force the user to deal with it before continuing with other actions (i.e., the user can access the main menu bar, switch applications, etc., without closing this window). A "modal" window, on the other hand, puts users in a mode where they must deal with options in the window before continuing.
Step 7. Add code that opens a modal window in response to selection of the "Open Dialog" menu item. Use a = 1010 (= FWND ID) and b = 0 (= modal) in NewWnd call.
Modal windows are opened, handled, and closed within isolated sections of program code with the ViewIt commands NewWnd, MdlWnd, and EndWnd, respectively:
if (fRec.uMenuID == 105)&&(fRec.uMenuItem == 1))
{
FaceIt(0,NewWnd,1010,0,0,0);
FaceIt(0,MdlWnd,1010,0,0,0);
FaceIt(0,EndWnd,1010,0,0,0);
}
Recompile and rerun the program. Choose "Open Dialog". The first time you do this you'll get a message from ViewIt saying that FWND 1010 will be added to your resource file. Do it. A default window will then appear containing one view and one button control. Press the button control to close the window (this drops us out of the MdlWnd call in your code, which then calls EndWnd to close the window).
Further information:
ViewIt -> Windows
Window Commands -> NewWnd, MdlWnd, EndWnd
8. Buttons
Button controls are like menu items - a hit in one results in the program receiving a simple message: uMenuID = FWND ID of parent window and wcHit = number of control. Buttons are one of the most common items added to windows.
Step 8. Run the "Tutorial" program, open the dialog, and enter edit mode (Option-Command-Shift). Use the Import menu (the "+" menu) to add a "Standard" button to the window. Double-click the new button to open the Title dialog and change the button's title to "Run". Before leaving edit mode, choose "Save All to disk" from the File menu to save your changes. (Whenever a change in a window is made that you want to save, be certain to use "Save All to disk" to update the FWND on disk.)
ViewIt's Import menu contains examples of controls that can be added to ViewIt windows. The "Editing" topic in the ViewIt guide describes how you can add any number of other control types to the Import menu.
If you enter edit mode, select the new "Run" button, and open the Control dialog (by triple-clicking or choosing "Control" from the window icon menu), then the following settings are displayed for this control:
- Behavior: "Button" type control, "Returns On Hit" (returns a message when hit), is not the default button (does not respond to Enter or Return keys)
- Resource Link: none
- Values: Min = 0, Max = 1, Value = 0
- Driver: CDEF 0 (Apple's standard CDEF)
These settings are typical of standard button-type controls.
Further information:
ViewIt -> Editing -> Import Menu
Drivers -> CDEFs
9. Modal Events
Both buttons in the program's modal dialog generate a message when hit (since they both have "Returns On Hit" checked in the Control dialog). Code is needed to respond to these messages.
Step 9. Add an event loop around MdlWnd with code to handle hits in the "OK" and "Run" buttons (uMenuID = 1010, wcHit = 1 or 2), and the window's close box (uMenuID = 1010, wcHit = -1).
Since both buttons and the close box return uMenuID = 1010, and these are the only messages returned, we could get away with checking only wcHit, but we'll also check uMenuID since other types of controls added later can return different values of uMenuID:
FaceIt(0,NewWnd,1010,0,0,0);
for (;;) {
FaceIt(0,MdlWnd,1010,0,0,0);
if (fRec.uMenuID == 1010) {
if (fRec.wcHit == -1)
break;
else if (fRec.wcHit == 1)
break;
else if (fRec.wcHit == 2) {
}
}
}
FaceIt(0,EndWnd,1010,0,0,0);
where the "OK" button (wcHit = 1) now drops us out of the loop, but the "Run" button (wcHit = 2) remains in the loop (i.e., the window stays open after "Run" is hit). Recompile and rerun the program to test the buttons and close box.
TIP: This tutorial and other demos often use wcHit and wvHit to identify controls within ViewIt windows to emphasize the hierarchical relationship of controls within views. In practice, however, many programmers assign an "item ID" to controls (set in Title or Control dialog), which can be any number from -32767 to +32767. This item ID is returned in wiHit, and will not be affected by changes in the ordering of controls in the window (i.e., you can add, remove, and reorder controls in the window without worrying about updating program code).
Further information:
ViewIt -> Windows -> Modal Windows -> Item Events
ViewIt -> Windows -> Closing Windows
The next few steps illustrate how to transfer information between your program and controls in a ViewIt window.
10. Check Box
In addition to buttons that return messages when hit, most dialogs contain other controls which are used to display and/or obtain information: check boxes, radio buttons, static text, editable text, scrollable lists, pop-up menus, etc.
Step 10. Run the "Tutorial" program, open the dialog, and enter edit mode (Option-Command-Shift) again. Use the Import menu (the "+" menu) to add a "Standard" check box to the window.
Check boxes are used to display one of 2 states: on (checked) or off (unchecked). ViewIt supports many different types of check boxes, but you'll probably want to become familiar with using the standard check box before exploring other options.
Further information:
Drivers -> CDEFs
11. Editable Text
Single strings are typically displayed in either non-editable static text or editable text controls.
Step 11. From within edit mode, use the Import menu to add an editable "Text w/ Frame" control to the window.
While in edit mode, select the editable text control and open the Control dialog to view the following settings:
- Behavior: "Editable" type control, "Idle" message sent (for flashing the text insertion bar)
- Resource Link: none
- Driver: BaseCt 2.2 (FCMD 1310)
Note that this control's driver is BaseCt 2.2, which is a module included with ViewIt that supports common control types that Apple's standard CDEF's don't support. Click the "Driver Help" button in the Control dialog or choose "BaseCt" from "Drivers" menu in this window to view more information about BaseCt.
Further information:
Drivers -> BaseCt -> Editable Text
12. Scrollable List
Lists of strings can be displayed in scrollable list controls.
Step 12. From within edit mode, use the Import menu to add a scrollable "Strings (STR#)" list to the window.
While in edit mode, select the scrollable list control and open the Control dialog to view the following settings:
- Behavior: "List or Menu" type control
- Resource Link: STR# 1316
- Variation Code: 128 (single selection list)
- Driver: BaseCt 2.2 (FCMD 1310)
This control is also supported by BaseCt, but differs from all other controls in the window by being linked to a resource: STR# 1316. This linked resource is part of the BaseCt module since its ID number is in the range of IDs used by BaseCt (‚â• 1310), and is provided as an example of an STR# resource linked to a scrollable list control. You should replace the use of STR# 1316 with a string list in your own resource file. The simplest way to do this is to start by saving a copy of STR# 1316 to your resource file:
Step 12 continued. While still within edit mode with the Control dialog open showing settings for the scrollable list, change 1316 in the resource "ID" field to 1005, and then choose "Add Resource" from the ResEdit icon menu to add a copy of STR# 1316 to your resource file as STR# 1005.
STR# 1005 can then be edited with ResEdit or other resource editor and changes to the STR# will affect the strings displayed in the scrollable list control.
Further information:
Drivers -> BaseCt -> Scrollable Lists
13. Pop-Up Menu
The basic control driver, BaseCt, also supports a variety of pop-up menu controls.
Step 13. From within edit mode, use the Import menu to add a "Pop-Up (MENU)" menu control to the window.
While in edit mode, select the pop-up menu control and open the Control dialog to view the following settings:
- Behavior: "List or Menu" type control
- Resource Link: MENU 1314
- Variation Code: 13 (= single select (1) + display above (4) + auto process(8))
- Driver: BaseCt 2.2 (FCMD 1310)
This is another BaseCt control. It is distinguished from other controls by being linked to a MENU resource, and differs from other menu controls by its Variation Code. As with STR# 1316 linked to the scrollable list control, MENU 1314 is just an example of a MENU resource, and should be replaced with a MENU resource in your resource file.
What MENU resource ID and menu ID should be used with the new menu control? MENUs used by menu controls do not need to be auto-loaded by FaceIt, so use resource IDs that are outside the range of IDs auto-loaded by FaceIt. The major consideration in picking the menu control's internal menu ID is that it should not conflict with an existing message returned in uMenuID (i.e., don't pick a menu ID that is equal to that used by another active menu control or the FWND ID of an existing window). For consistency, we'll use the same scheme to number the new menu control's menu ID as that used with the program's main menus: menu ID = resource ID - 900.
Step 13 continued. While still within edit mode with the Control dialog open showing settings for the pop-up menu, change 1314 in the resource "ID" field to 1021, and then choose "Add Resource" from the ResEdit icon menu to add a copy of MENU 1314 to your resource file as MENU 1021.
MENU 1021 can then be edited with ResEdit or other resource editor. Set this MENU resource's internal menu ID to 121.
Further information:
Drivers -> BaseCt -> Menu Controls
14. Data Links
There are now several controls in the dialog that can be used to convey information between the program and the user. While in edit mode, check that the controls in the dialog are in the following order:
1. "OK" button
2. "Run" button
3. check box
4. editable text
5. scrollable list
6. pop-up menu
where the order can be modified with the alignment menu or by dragging the rounded rectangles in the controls bar at the right of the window. Save changes with "Save All to disk".
We can use ViewIt's "data linking" to move information to and from the 4 new controls.
Step 14. Create 4 program variables, initialize them, and link them to the 4 new controls in the dialog.
Any variable type can be linked to any control type and ViewIt does the work of translating from one to the other. In the case of the 4 controls added to the dialog, we will link integers to the check box, scrollable list, and pop-up menu, and a string to the editable text item (other combinations are shown in the other demo programs accompanying ViewIt):
short theFlag,theListItem,theMenuItem;
char theString[32];
...
theFlag = 0; <- check box not checked
theListItem = 3; <- 3rd item in list selected
theMenuItem = 2; <- 2nd item in pop-up shown
strcpy(theString, "Hello"); <- "Hello" in editable text
...
FaceIt(0,NewWnd,1010,0,0,0);
FaceIt(0,GetCtl,1010,0,1,3);
FaceIt(0,LnkCtl,(long)fRec.cControl,
(long)&theFlag,2,0);
FaceIt(0,GetCtl,1010,0,1,4);
FaceIt(0,LnkCtl,(long)fRec.cControl,
(long)theString,-31,0);
FaceIt(0,GetCtl,1010,0,1,5);
FaceIt(0,LnkCtl,(long)fRec.cControl,
(long)&theListItem,2,0);
FaceIt(0,GetCtl,1010,0,1,6);
FaceIt(0,LnkCtl,(long)fRec.cControl,
(long)&theMenuItem,2,0);
for (;;) {
FaceIt(0,MdlWnd,1010,0,0,0);
...
Important Note: A surprising number of programmers ask us "Why must I initialize linked variables if all I'm interested in is what the user returns to my program?". The reason is that the initial state of linked controls in a window should reflect either the "current", "default", or "most likely" state of the linked variable. This informs the user of current settings, and/or helps them make more reasonable choices.
The above code illustrates how a pair of calls to GetCtl and LnkCtl is required to link each variable to a control in the dialog. The parameters passed to LnkCtl are:
a = control handle which uniquely identifies the control
b = memory address of program variable to be linked
c = data type of program variable being linked
where the data type is obtained from the table presented in the "Data Links" topic of the ViewIt guide. Other examples of data linking appear in the vDemoXY program.
Once linked, the ViewIt commands SetVal and GetVal can be used to move information to and from controls in the window.
Step 14 continued. Add calls to SetVal and GetVal to move information to and from the dialog.
Although several calls were needed to set up data links, only one SetVal or GetVal command is needed to set or get all values:
...
FaceIt(0,SetVal,1010,0,0,0);
for (;;) {
FaceIt(0,MdlWnd,1010,0,0,0);
...
else if (fRec.wcHit == 1) {
FaceIt(0,GetVal,1010,0,0,0);
break;
}
...
where SetVal causes ViewIt to update the contents of the dialog with the current values of variables "theFlag", "theString", "theListItem", and "theMenuItem", and GetVal copies the current contents of the dialog back to these variables (which in this case only happens if the user hits "OK"). Recompile and rerun the "Tutorial" program to verify that data linking is working properly for the 4 controls now linked to variables.
Further information:
ViewIt -> Data Links
Control Commands -> GetCtl, LnkCtl, GetVal, SetVal
The final steps illustrate features of more advanced controls and how your program can use these to output results.
15. Editable Controls
"Editable" controls (those whose behavior is set as "Editable" in ViewIt's Control dialog) exhibit more complex behavior than buttons, check boxes, radio buttons, lists, menus, and other non-editable controls. Editable controls can be "selected" in the sense that they can become the focus of menu selections and key events. If the editable text control in the dialog is selected, for example, then it receives all key events, changes the cursor to a text insertion bar when above the control, and selections in standard menu items such as "Cut", "Copy", and "Paste" will affect the text in the editable text control.
Step 15. Open the dialog again, enter edit mode, and add a "Pull-Down (MENU)" control, which contains standard menu items. (If desired, use ViewIt's Bounds dialog to add a frame to this control by setting the frame's pen size to a value greater than 0.) Use "Add Resource" to save a copy of the linked MENU resource as MENU 1022 to your resource file (as described above).
The standard items in the menu added will affect the text in the editable text control, illustrating that, even in modal dialogs, the entire range of standard behavior supported by a control can be accessed via pull-down menu controls.
Further information:
FaceIt -> Menu Handling
ViewIt -> Windows -> Modal Windows -> Editable Items
ViewIt -> Windows -> Modal Windows -> Special Keys
16. Advanced Controls
Any number of editable controls can be added to a window, and the user can tab or click between them to change the focus from one to another (i.e., to change which is selected). FaceWare distributes a set of advanced, editable controls that include support for printing and file handling of their contents: the EditControls, QuickControl, and CommControl products. Even if you do not own one of these, you can see a TextCt control (part of EditControls) displayed within the fDemoXY program. To illustrate use of such an advanced control, we'll add a TextCt control to our dialog window. The first step is to make the TextCt module available to the Tutorial program.
Step 16. Run the MoveIt program and use it to move the TextCt module from "fDemoXY.Rsrc" to "Tutorial.Rsrc" (or to the shared FaceWare file).
Once the module is available, then a TextCt-based control can be added to our dialog window.
Step 16 continued. Run the fDemoXY program, bring its "Editor" window forward, enter edit mode, select the control in the middle of the window (a TextCt control), and copy it as an FCTL resource ("Copy FCTL" in File icon menu). Then run the Tutorial program again and paste the FCTL into its dialog window when in edit mode (you may need to move/resize controls to make room).
The TextCt control pasted into the dialog window is linked to a special "TREC" resource which saves TextCt settings. If this TREC is missing, then ViewIt just displays an error message in place of the TextCt control.
Step 16 continued. Use ResEdit or other resource editor to copy the TREC resource needed by the TextCt control from fDemoXY.Rsrc and paste it into Tutorial.Rsrc.
Rerun the Tutorial program to check that the TextCt control behaves like an editable control. This control also supports file handling and printing, but you cannot test this since the window is modal and no menu has been added to it with standard file or print items.
Step 16 continued. Use ResEdit or other resource editor to add an "Open...#2" item to MENU 1022 which is linked to the pull-down menu added earlier.
This illustrates how you can add standard menu items to any menu in any window to support standard features supported by advanced editable controls. Which standard items are supported by a control will be documented in the driver's on-line help. Rerun the Tutorial program and try the new "Open" item.
Further information:
Drivers -> TextCt
FaceIt -> Menu Handling
17. Attached Controls
The TextCt control is usually attached to the right and bottom sides of its parent view, which is in turn attached to the right and bottom sides of the window to support zoom and grow boxes.
Step 17. While in edit mode, select the dialog's view control, open the Bounds dialog, and attach the view to the right and bottom sides of the window. Then select the TextCt control and attach it to the right and bottom sides of the view. When you leave edit mode, the view and TextCt control will be resized to comply with these new settings. If the window does not have grow and zoom boxes, reenter edit mode, open the Window dialog, and change settings to support a grow and zoom box.
Any number of views and controls can be attached in the same window, and ViewIt will use these attachments to control sizing of the window. Try resizing the window and watch what happens to the attached view and control.
Further information:
ViewIt -> Views -> The View Driver -> Attached Views
ViewIt -> Controls -> Growing
18. Program Output
The high-capacity TextCt controls are useful for storing text output. The final step in the tutorial is to add a little code that outputs text in response to a hit in the dialog's "Run" button:
Step 18. Add code that outputs text to the TextCt control in response to a hit in the "Run" button.
The following code assumes that the TextCt control is control #8 in the dialog. The command "1565" is the numerical value of the TextCt command LineCIO (to learn more about this you will need to purchase the EditControls product), and passing the control's handle as the first parameter is the typical way that programs communicate directly with advanced controls.
for (;;) {
FaceIt(0,MdlWnd,1010,0,0,0);
...
else if (fRec.wcHit == 2) {
FaceIt(0,GetCtl,1010,0,1,8);
strcpy(fRec.uString,"Run button was hit.");
FaceIt(fRec.cControl,1565,2,0,0,0);
}
...
Recompile and rerun the Tutorial program to verify that the string "Run button was hit." appears in the TextCt control each time the "Run" button is hit.
Further information:
Drivers -> TextCt
Congratulations! You've built your first program using ViewIt and FaceIt to which you have added a new menu and window, a variety of controls to the window, plus the code to support all of these interface objects. To learn more, study the other demo programs and the topics in the ViewIt and FaceIt guides.
